Config Port Overview & Best Practices

Config Port is a powerful tool for developing and transferring screens, email templates, and system settings between systems; however if used incorrectly problems may occur. This topic contains an overview explaining the basic principles behind Config Port, as well as recommended best practices to avoid the common pitfalls. A detailed explanation of Config Port is available in the Configuration Portability topic.

Terms Used

  • The Production (PROD) system is the master target system - the final destination for all the changes being developed
  • The Development (DEV) system is the source system - where all the changes are developed
  • The Test system is the target system - where the import is tested priority to import into Production

How Config Port Works

Export

  • On the Config Port Source (DEV) environment the elements to export are selected
    • Config Port is run and the data exported to file
  • Where there is a null CONFIG_PORT_GUID the value is allocated
    • Static records are allocated static GUIDs during install and patch
    • User-created records are allocated GUIDs during export, the GUIDs are created by an algorithm
    • User-created records are allocated GUIDs a record at a time, and then all are exported to file

Import

  • On the Target system areas to import are selected from export file
    • Config Port is run and the data imported
  • GUIDs from the Config Port Source (DEV) are matched to GUIDs on the Target environment
    • If there is no match on GUID, various properties of the item are looked up, generally name and partition
    • When matching on properties, the Config Port excludes all items with a GUID
    • If a match on properties is identified:
      • the GUID is set so the items are always in sync in the future (between the Source and Target environments)
      • other properties are updated (i.e. status)
    • If there is no match on GUID and no match on defined properties, a new record is created on the Target environment with the GUID set from the Source environment (DEV)

Best Practice

Required Export / Import Sequence

The import and export sequence is critically important to a successful outcome. Follow these steps to ensure all changes are developed on the correct database and imported successfully to the master target system.

  1. Copy the Production database to your development environment.

    2. For detailed instructions refer to Copying the Production System to a Test Environment.

  2. Develop the required screens, emails, and system setting changes on the DEV system
  3. When complete, run Config Export on the DEV system to create a config file
  4. Copy the Production database to your test environment.
  5. Run Config Import on the test system
  6. Perform tests on the test system to ensure the import was successful
    • If testing reveals there were problems with the changes or the import, go back to Step 2.
  7. Run Config Import on the PROD system using the config file from step 3.
    • Back up the PROD database prior to import

More Best Practice Recommendations

There can be only one Config Port Source, and one Master Target

  • The Config Port Source is typically a DEV environment, the Master Target is Production (PROD)
  • Before backing up the Master Target (PROD), always run the Config Portability GUID Assignment.scp from the Server Console – this fills any blank static GUIDS to prevent mismatches

Version alignment

  • Source and Target environments need to be the same VSM/vFire patch version
    • i.e. Major.Minor.Maintenance values must match across environments
  • After a vFire upgrade, the Config Port Source (and any other Target environments) should always be overwritten with a new database copy from the Master Target (PROD)

Back up the Target environment(s)

  • Backup routine should always occur prior to porting to facilitate rollback if needed

Code and configuration freeze on Target environment(s)

  • Configuration changes should only be made on the Source system (DEV) and then ported
  • Manual changes should not be performed on Master Target (PROD) or other Target (TEST) environments
    • Manual changes risk being overwritten by the porting process

Be specific

  • Only port the specific elements you want to port
    • Config Port will maintain system/data relationships; i.e. porting a specific request screen will also port across any dependent data linked to that screen (linked fields in the screen set, fields linked to the parent request screen set and lookup data)

Typical Mistakes

That can cause data corruption

  • Config Port Source (DEV) and other Targets are not synced with the Master Target (PROD) before development starts
  • Config file from Target (TEST) is imported into Master Target (PROD), instead of the Config file from Source (DEV)
  • Importing Config files from multiple environments into Master Target (PROD)
  • No Test environment
  • Exporting from an environment that has partitioning enabled, and importing into a system that does not (and vice versa) may result in errors in the export and/or import process. In addition, partition names must be unique across Source and Target(s) for the process to be successful

That confuse Administrators

  • Expectation that Workflow Templates are ported as part of Config Port
  • Not running Config Port and Workflow Port in the correct sequence, which is:

      Config Port -> Workflow Port -> Config Port (if Workflow Port log has warnings)

  • Expectation that exporting a child item (e.g. email template) also exports the parent item (e.g. screen set)